Skip to content

feat(nav3): [Part 10] Use built-in BackStackEntryMappers in the Nav3 sample app - #6707

Open
0xadam-brown wants to merge 2 commits into
feat/nav3-serial-name-mappers-9from
feat/nav3-serial-name-mappers-10
Open

0xadam-brown wants to merge 2 commits into
feat/nav3-serial-name-mappers-9from
feat/nav3-serial-name-mappers-10

Conversation

@0xadam-brown

@0xadam-brown 0xadam-brown commented Nov 20, 2026 •

Copy link
Copy Markdown
Member

PR Stack (Nav3 Serial Name Mappers)


📜 Description

PR updates the Nav3 sample app to make use of the new built-in BackStackEntryMappers.

PR also extends the sample app's Performance tab to allow for performance testing against the new mappers.

💡 Motivation and Context

The performance scenario needs to distinguish the cost of real built-in mapping from synthetic name and argument workloads. It therefore keeps the custom performance mapper and adds a choice to exercise the built-in mapper itself, so measurements can reflect the path an application would actually use.

addresses: JAVA-787 (link)

⚠️ Callouts

No performance or related issues identified in connection withthis PR stack.

I had my clankers do some deep dives w/r/t whether this PR stack introduces any performance issues, memory leaks, or opportunities to crash the host app. No issues were found. Here's a summary:

Performance

JVM microbenchmark

Measured on the JVM through the real BackStackConverter: 5 entries per update (the default capture size), each with 7 properties including a list, a map, and a sensitive key. Warmup 20k iterations, timed over 50k.

Mapper Time / update Allocation / update vs. custom mapper
Custom mapper returning a prebuilt map 3–4 µs ~10.8 KB baseline
SerialName (names only) 0.3–0.5 µs ~1.2 KB ~10× cheaper
SerialNameAndProperties 9–10 µs ~10.2 KB ~2.5× CPU, similar memory
SerialNameAndProperties, serializer throws every update ~11 µs ~14.6 KB +exception cost

On-device confirmation (emulator, API 36)

Ran the Nav3 sample's stress scenario with a new Mapper toggle (Custom vs SerialNameAndProperties), Normal preset (back stack depth 20, capture 20), 20 measured iterations per run. Numbers are the published diagnostics read from logcat.

Fixed runs — mutation → composition p50:

Run Custom SerialNameAndProperties
Top replacements 16.00 ms 16.70 ms
Lower mutations (top stays put) 18.37 ms 18.75 ms

A/B comparison (integration disabled vs full stack) — first-draw p50:

Mapper Disabled Full stack Delta
Custom 32.85 ms 32.82 ms ~0 ms (noise)
SerialNameAndProperties 32.86 ms 33.20 ms +0.34 ms

The built-in mapper tracks the custom mapper within run-to-run noise on every run, including the "top stays put" lower-mutation run. The whole integration's on-device cost — encoding included — is sub-millisecond per update at the frame level, consistent with the ~10 µs JVM figure being lost against a ~16–33 ms Compose frame. Emulator numbers; a low-end physical device is slower in absolute terms, but the custom-vs-built-in gap being within noise should hold since both walk the same sanitizer pipeline.

Concern Assessment
Absolute cost ~10 µs/update on JVM. Even at 10× on Android that's ~0.1 ms, and updates happen per navigation, not per frame. Not user-perceptible.
Repeated work on the Compose apply thread Pre-existing: main already re-converted entries on every observed stack change, including when the top is unchanged. The branch adds serializer calls into that loop for SerialNameAndProperties. Value/text/depth limits already existed.
Upper bound on large routes / deep stacks Self-limiting: once the shared per-update budget (200 values / 4,096 chars) is spent, later entries skip encoding entirely. Cost does not grow unbounded.
Failing types Encoding is retried every update (warnings still log once per type). Each retry allocates an exception + stack trace, costlier on Android under deep Compose stacks — but bounded by the ≤5 captured entries. Optional: cache value-independent SerializationExceptions per type to stop the retries.
Writer allocations New: one TreeArgumentWriter + IdentityHashMap + container stacks per entry with arguments (previously one identity map per update). Didn't register at this size. Optional: allocate the identity map lazily on first container.
Double denylist scan New, specific to built-in property encoding (encoder checks keys, SensitiveKeyFilter re-checks as a safeguard). Bounded by the budget; didn't register at this size.
One-time costs Each mapper runs its compatibility probe once on first access (usually in composition); each new route type then costs one reflective serializer lookup on the main thread. Nav3 typically has already loaded these serializers to persist the back stack.

Conclusion: No performance issue that warrants a design change before merge. The on-device run confirmed the built-in mapper is within noise of a custom mapper, including rapid stack changes where the top stays put, so the duplicate denylist scan and per-entry identity tracking don't need changing.

Memory

Area What's retained Lifetime Leak? Notes
Mapper type caches ConcurrentHashMaps keyed by Class holding each route type's name, serializer, "has properties" flag, and which warnings were already logged Whole process (the mappers are process-wide vals) No Bounded by the number of distinct back stack key types, which is small and fixed per app. Keys are strongly held, so the route classes can't be unloaded — a non-issue on Android, where app route classes live for the process. A weak key wouldn't help anyway, because the cached serializer pins the class.
KotlinxArguments map The original route entry, its KSerializer, the onFailure callback, and the lazily encoded copy As long as the map is reachable No The SDK does not keep these past one back stack update: BackStackObserver stores only the sanitized plain-map output and a WeakReference to the previous top entry. The route is only held longer if the host keeps the mapper's result, and the host already holds its own back stack key. KDoc now states this (commit 408281228a).
Per-update writer state TreeArgumentWriter with its IdentityHashMap and container/identity stacks One entry's conversion No Allocated per entry that has arguments and discarded immediately. Short-lived garbage, not retention.
Logger reference Resolved on each use via ScopesAdapter.getInstance().options.logger Per call No Never caches a closed SDK's options or logger.
Scope-bound nav data Arguments copied into the breadcrumb, transaction data, transaction context, and the scope's Navigation context (persisted to disk on Android each update) Scope lifetime No (pre-existing) Same mechanism as main. The change is that SerialNameAndProperties sends arguments by default, so more apps populate these. Still capped by the shared per-update budget (200 values / 4,096 characters). Custom mappers with arguments already behaved this way.

Conclusion: No new memory leak. The Activity watcher, lifecycle disposal, and the WeakReference to the previous top entry all predate the branch and were re-checked.

Crashing the host app

Entry point Failure modes handled Can still escape Severity
Mapper creation (first access to SerialName / SerialNameAndProperties) create() catches LinkageError (missing/incompatible kotlinx, ART verification failure of the AbstractEncoder subclass, ExceptionInInitializerError); the compatibility probe catches all other non-fatal errors and reports them as inconclusive A fatal VM error, or a host logger that itself throws from a diagnostic call during creation Low. The logger case is an SDK-wide pattern (nothing in the SDK guards the logger); notable here only because creation usually runs in composition.
map() Annotation check, serializer lookup, descriptor access, and the "has properties" check are each guarded; LinkageError and other non-fatal throwables are caught and cached per type as /unknown Fatal errors only Safe, including when host code calls map() directly (as the sample does).
Reading / writing arguments (KotlinxArguments, encoder) All non-fatal errors during encoding are caught, including per-type LinkageError; serializer misuse (e.g. an unbalanced endStructure()) surfaces as encoding_failed; the one internal check() is unreachable from host paths Fatal errors only Safe.
Stack overflow / deep recursion Bounded by MAX_SERIALIZER_NESTING (64) and MAX_ARGUMENT_DEPTH (10) — roughly ~1,000 frames, well within the main-thread stack A serializer that recurses into itself without nesting properties can overflow before reaching the guards Expected. Such a serializer overflows under any kotlinx output format; rethrowing StackOverflowError follows AGENTS.md's fatal-error policy.
Fatal errors generally ExceptionUtils.rethrowIfFatal is applied before every broad catch OutOfMemoryError, StackOverflowError, LinkageError (where fatal), etc. are rethrown by design Expected and correct.

Conclusion: No new way to crash the host under normal operation. The only non-fatal escape is a throwing host logger, which is a pre-existing SDK-wide behavior; the one new call site worth noting is mapper creation during composition. Optional hardening: wrap the diagnostic calls in the mapper constructor.

💚 How did you test it?

Nav3 release build and all 872 unit tests passed. Repository-wide make format api, Spotless checks, ABI validation, and Detekt passed. The Android sample debug build passed after including its shared serialization-plugin setup in this slice.

📝 Checklist

  • I added GH Issue ID & Linear ID
  • I added tests to verify the changes.
  • No new PII added or SDK only sends newly added PII if sendDefaultPII is enabled.
  • I updated the docs if needed.
  • I updated the wizard if needed.
  • Review from the native team if needed.
  • No breaking change or entry added to the changelog.
  • No breaking change for hybrid SDKs or communicated to hybrid SDKs.
  • Public API changes reviewed by another Mobile SDK team member or implemented according to the develop docs spec.

🔮 Next steps

Continue with PR 11: Verify mapping after R8 minification.

⚠️ Merge this PR using a merge commit (not squash). Only the collection branch is squash-merged into main.

#skip-changelog

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor
Messages
📖 Do not forget to update Sentry-docs with your feature once the pull request gets approved.

Generated by 🚫 dangerJS against f7b850a

@github-actions github-actions Bot added the risk: medium PR risk score: medium label Nov 20, 2026
@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

PR risk: medium

For commit f7b850a.

The model rated this change low. It was raised to medium because:

  • R6: build or release configuration changed: sentry-android-integration-tests/build.gradle.kts, sentry-android-integration-tests/sentry-samples-android/build.gradle.kts
  • R7: the model was not confident enough that the change is low

This label is a hint for reviewers, not an approval.

@github-actions github-actions Bot added risk: medium PR risk score: medium and removed risk: medium PR risk score: medium labels Nov 20, 2026
@github-actions github-actions Bot added risk: medium PR risk score: medium and removed risk: medium PR risk score: medium labels Nov 20, 2026
@sentry

sentry Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

📲 Install Builds

Android

🔗 App Name App ID Version Configuration
SDK Size io.sentry.tests.size 8.65.0 (1) release

⚙️ sentry-android Build Distribution Settings

@0xadam-brown
0xadam-brown force-pushed the feat/nav3-serial-name-mappers-10 branch from 7a34760 to f7b850a Compare November 20, 2026 14:00
@github-actions github-actions Bot added risk: medium PR risk score: medium and removed risk: medium PR risk score: medium labels Nov 20, 2026
@0xadam-brown 0xadam-brown changed the title feat(nav3): [Nav3 Mappers 10] Demonstrate the built-in mappers feat(nav3): [Part 10] Demonstrate the built-in mappers Nov 20, 2026
@0xadam-brown 0xadam-brown changed the title feat(nav3): [Part 10] Demonstrate the built-in mappers feat(nav3): [Part 10] Use built-in BackStackEntryMappers in the Nav3 sample app Nov 20, 2026
@0xadam-brown
0xadam-brown marked this pull request as ready for review November 20, 2026 15:51
@0xadam-brown
0xadam-brown requested review from a team and adinauer as code owners November 20, 2026 15:51
@0xadam-brown
0xadam-brown requested review from markushi and runningcode and removed request for a team November 20, 2026 15:51
@github-actions github-actions Bot added risk: medium PR risk score: medium and removed risk: medium PR risk score: medium labels Nov 20, 2026
@0xadam-brown 0xadam-brown added the sanity-check PR needs a lightweight review for obvious issues label Nov 20, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

risk: medium PR risk score: medium sanity-check PR needs a lightweight review for obvious issues

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant